home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / libgimp / sgml / gimpdialog.sgml < prev    next >
Encoding:
Text File  |  2003-05-20  |  15.0 KB  |  306 lines
  1. <refentry id="libgimp-gimpdialog" revision="19 Jan 2001">
  2. <refmeta>
  3. <refentrytitle>gimpdialog</refentrytitle>
  4. <manvolnum>3</manvolnum>
  5. <refmiscinfo>LIBGIMP Library</refmiscinfo>
  6. </refmeta>
  7.  
  8. <refnamediv>
  9. <refname>gimpdialog</refname><refpurpose>Constructors for <link linkend="GtkDialog">GtkDialog</link>'s and action_areas as well as other
  10. dialog-related stuff.</refpurpose>
  11. </refnamediv>
  12.  
  13. <refsynopsisdiv><title>Synopsis</title>
  14. <synopsis>
  15.  
  16.  
  17.  
  18. <link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gimp-dialog-new">gimp_dialog_new</link>                 (const <link linkend="gchar">gchar</link> *title,
  19.                                              const <link linkend="gchar">gchar</link> *wmclass_name,
  20.                                              <link linkend="GimpHelpFunc">GimpHelpFunc</link> help_func,
  21.                                              const <link linkend="gchar">gchar</link> *help_data,
  22.                                              <link linkend="GtkWindowPosition">GtkWindowPosition</link> position,
  23.                                              <link linkend="gint">gint</link> allow_shrink,
  24.                                              <link linkend="gint">gint</link> allow_grow,
  25.                                              <link linkend="gint">gint</link> auto_shrink,
  26.                                              ...);
  27. <link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gimp-dialog-newv">gimp_dialog_newv</link>                (const <link linkend="gchar">gchar</link> *title,
  28.                                              const <link linkend="gchar">gchar</link> *wmclass_name,
  29.                                              <link linkend="GimpHelpFunc">GimpHelpFunc</link> help_func,
  30.                                              const <link linkend="gchar">gchar</link> *help_data,
  31.                                              <link linkend="GtkWindowPosition">GtkWindowPosition</link> position,
  32.                                              <link linkend="gint">gint</link> allow_shrink,
  33.                                              <link linkend="gint">gint</link> allow_grow,
  34.                                              <link linkend="gint">gint</link> auto_shrink,
  35.                                              va_list args);
  36. void        <link linkend="gimp-dialog-set-icon">gimp_dialog_set_icon</link>            (<link linkend="GtkWindow">GtkWindow</link> *dialog);
  37. void        <link linkend="gimp-dialog-create-action-area">gimp_dialog_create_action_area</link>  (<link linkend="GtkDialog">GtkDialog</link> *dialog,
  38.                                              ...);
  39. void        <link linkend="gimp-dialog-create-action-areav">gimp_dialog_create_action_areav</link> (<link linkend="GtkDialog">GtkDialog</link> *dialog,
  40.                                              va_list args);
  41. </synopsis>
  42. </refsynopsisdiv>
  43.  
  44.  
  45.  
  46.  
  47.  
  48. <refsect1>
  49. <title>Description</title>
  50. <para>
  51.  
  52. </para>
  53. </refsect1>
  54.  
  55. <refsect1>
  56. <title>Details</title>
  57. <refsect2>
  58. <title><anchor id="gimp-dialog-new">gimp_dialog_new ()</title>
  59. <programlisting><link linkend="GtkWidget">GtkWidget</link>*  gimp_dialog_new                 (const <link linkend="gchar">gchar</link> *title,
  60.                                              const <link linkend="gchar">gchar</link> *wmclass_name,
  61.                                              <link linkend="GimpHelpFunc">GimpHelpFunc</link> help_func,
  62.                                              const <link linkend="gchar">gchar</link> *help_data,
  63.                                              <link linkend="GtkWindowPosition">GtkWindowPosition</link> position,
  64.                                              <link linkend="gint">gint</link> allow_shrink,
  65.                                              <link linkend="gint">gint</link> allow_grow,
  66.                                              <link linkend="gint">gint</link> auto_shrink,
  67.                                              ...);</programlisting>
  68. <para>
  69. This function simply packs the action_area arguments passed in "..."
  70. into a <parameter>va_list</parameter> variable and passes everything to <link linkend="gimp-dialog-newv">gimp_dialog_newv</link>().
  71. </para>
  72. <para>
  73. For a description of the format of the <parameter>va_list</parameter> describing the
  74. action_area buttons see <link linkend="gimp-dialog-create-action-areav">gimp_dialog_create_action_areav</link>().</para>
  75. <para>
  76.  
  77. </para><informaltable pgwide=1 frame="none" role="params">
  78. <tgroup cols="2">
  79. <colspec colwidth="2*">
  80. <colspec colwidth="8*">
  81. <tbody>
  82. <row><entry align="right"><parameter>title</parameter> :</entry>
  83. <entry> The dialog's title which will be set with <link linkend="gtk-window-set-title">gtk_window_set_title</link>().
  84. </entry></row>
  85. <row><entry align="right"><parameter>wmclass_name</parameter> :</entry>
  86. <entry> The dialog's <parameter>wmclass_name</parameter> which will be set with
  87. <link linkend="gtk-window-set-wmclass">gtk_window_set_wmclass</link>(). The <parameter>wmclass_class</parameter> will be
  88. automatically set to "Gimp".
  89. </entry></row>
  90. <row><entry align="right"><parameter>help_func</parameter> :</entry>
  91. <entry> The function which will be called if the user presses "F1".
  92. </entry></row>
  93. <row><entry align="right"><parameter>help_data</parameter> :</entry>
  94. <entry> The data pointer which will be passed to <parameter>help_func</parameter>.
  95. </entry></row>
  96. <row><entry align="right"><parameter>position</parameter> :</entry>
  97. <entry> The dialog's initial position which will be set with
  98. <link linkend="gtk-window-set-position">gtk_window_set_position</link>().
  99. </entry></row>
  100. <row><entry align="right"><parameter>allow_shrink</parameter> :</entry>
  101. <entry> The dialog's <parameter>allow_shrink</parameter> flag, ...
  102. </entry></row>
  103. <row><entry align="right"><parameter>allow_grow</parameter> :</entry>
  104. <entry> ... it't <parameter>allow_grow</parameter> flag and ...
  105. </entry></row>
  106. <row><entry align="right"><parameter>auto_shrink</parameter> :</entry>
  107. <entry> ... it's <parameter>auto_shrink</parameter> flag which will all be set with
  108. <link linkend="gtk-window-set-policy">gtk_window_set_policy</link>().
  109. </entry></row>
  110. <row><entry align="right"><parameter>...</parameter> :</entry>
  111. <entry> A <link linkend="NULL-CAPS">NULL</link> terminated <parameter>va_list</parameter> destribing the action_area buttons.
  112. </entry></row>
  113. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A <link linkend="GtkDialog">GtkDialog</link>.
  114.  
  115. </entry></row>
  116. </tbody></tgroup></informaltable></refsect2>
  117. <refsect2>
  118. <title><anchor id="gimp-dialog-newv">gimp_dialog_newv ()</title>
  119. <programlisting><link linkend="GtkWidget">GtkWidget</link>*  gimp_dialog_newv                (const <link linkend="gchar">gchar</link> *title,
  120.                                              const <link linkend="gchar">gchar</link> *wmclass_name,
  121.                                              <link linkend="GimpHelpFunc">GimpHelpFunc</link> help_func,
  122.                                              const <link linkend="gchar">gchar</link> *help_data,
  123.                                              <link linkend="GtkWindowPosition">GtkWindowPosition</link> position,
  124.                                              <link linkend="gint">gint</link> allow_shrink,
  125.                                              <link linkend="gint">gint</link> allow_grow,
  126.                                              <link linkend="gint">gint</link> auto_shrink,
  127.                                              va_list args);</programlisting>
  128. <para>
  129. This function performs all neccessary setps to set up a standard GIMP
  130. dialog.
  131. </para>
  132. <para>
  133. The <parameter>va_list</parameter> describing the action_area buttons will be passed to
  134. <link linkend="gimp-dialog-create-action-areav">gimp_dialog_create_action_areav</link>().</para>
  135. <para>
  136.  
  137. </para><informaltable pgwide=1 frame="none" role="params">
  138. <tgroup cols="2">
  139. <colspec colwidth="2*">
  140. <colspec colwidth="8*">
  141. <tbody>
  142. <row><entry align="right"><parameter>title</parameter> :</entry>
  143. <entry> The dialog's title which will be set with <link linkend="gtk-window-set-title">gtk_window_set_title</link>().
  144. </entry></row>
  145. <row><entry align="right"><parameter>wmclass_name</parameter> :</entry>
  146. <entry> The dialog's <parameter>wmclass_name</parameter> which will be set with
  147. <link linkend="gtk-window-set-wmclass">gtk_window_set_wmclass</link>(). The <parameter>wmclass_class</parameter> will be
  148. automatically set to "Gimp".
  149. </entry></row>
  150. <row><entry align="right"><parameter>help_func</parameter> :</entry>
  151. <entry> The function which will be called if the user presses "F1".
  152. </entry></row>
  153. <row><entry align="right"><parameter>help_data</parameter> :</entry>
  154. <entry> The data pointer which will be passed to <parameter>help_func</parameter>.
  155. </entry></row>
  156. <row><entry align="right"><parameter>position</parameter> :</entry>
  157. <entry> The dialog's initial position which will be set with
  158. <link linkend="gtk-window-set-position">gtk_window_set_position</link>().
  159. </entry></row>
  160. <row><entry align="right"><parameter>allow_shrink</parameter> :</entry>
  161. <entry> The dialog's <parameter>allow_shrink</parameter> flag, ...
  162. </entry></row>
  163. <row><entry align="right"><parameter>allow_grow</parameter> :</entry>
  164. <entry> ... it't <parameter>allow_grow</parameter> flag and ...
  165. </entry></row>
  166. <row><entry align="right"><parameter>auto_shrink</parameter> :</entry>
  167. <entry> ... it's <parameter>auto_shrink</parameter> flag which will all be set with
  168. <link linkend="gtk-window-set-policy">gtk_window_set_policy</link>().
  169. </entry></row>
  170. <row><entry align="right"><parameter>args</parameter> :</entry>
  171. <entry> A <parameter>va_list</parameter> as obtained with <link linkend="va-start">va_start</link>() describing the action_area
  172. buttons.
  173. </entry></row>
  174. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A <link linkend="GtkDialog">GtkDialog</link>.
  175.  
  176. </entry></row>
  177. </tbody></tgroup></informaltable></refsect2>
  178. <refsect2>
  179. <title><anchor id="gimp-dialog-set-icon">gimp_dialog_set_icon ()</title>
  180. <programlisting>void        gimp_dialog_set_icon            (<link linkend="GtkWindow">GtkWindow</link> *dialog);</programlisting>
  181. <para>
  182. This function sets the WM pixmap icon for the dialog which will appear
  183. e.g. in GNOME's or KDE's window list.
  184. </para>
  185. <para>
  186. Note that this function is automatically called by
  187. <link linkend="gimp-help-connect-help-accel">gimp_help_connect_help_accel</link>() which in turn is called by
  188. <link linkend="gimp-dialog-newv">gimp_dialog_newv</link>(), so you only have to call it for <link linkend="GtkWindow">GtkWindow</link>'s which
  189. have no help page (like tear-off menus).</para>
  190. <para>
  191.  
  192. </para><informaltable pgwide=1 frame="none" role="params">
  193. <tgroup cols="2">
  194. <colspec colwidth="2*">
  195. <colspec colwidth="8*">
  196. <tbody>
  197. <row><entry align="right"><parameter>dialog</parameter> :</entry>
  198. <entry> The <link linkend="GtkWindow">GtkWindow</link> you want to set the pixmap icon for.
  199. </entry></row>
  200. </tbody></tgroup></informaltable></refsect2>
  201. <refsect2>
  202. <title><anchor id="gimp-dialog-create-action-area">gimp_dialog_create_action_area ()</title>
  203. <programlisting>void        gimp_dialog_create_action_area  (<link linkend="GtkDialog">GtkDialog</link> *dialog,
  204.                                              ...);</programlisting>
  205. <para>
  206. This function simply packs the action_area arguments passed in "..."
  207. into a <parameter>va_list</parameter> variable and passes everything to
  208. <link linkend="gimp-dialog-create-action-areav">gimp_dialog_create_action_areav</link>().</para>
  209. <para>
  210.  
  211. </para><informaltable pgwide=1 frame="none" role="params">
  212. <tgroup cols="2">
  213. <colspec colwidth="2*">
  214. <colspec colwidth="8*">
  215. <tbody>
  216. <row><entry align="right"><parameter>dialog</parameter> :</entry>
  217. <entry> The <link linkend="GtkDialog">GtkDialog</link> you want to create the action_area for.
  218. </entry></row>
  219. <row><entry align="right"><parameter>...</parameter> :</entry>
  220. <entry> A <link linkend="NULL-CAPS">NULL</link> terminated <parameter>va_list</parameter> destribing the action_area buttons.
  221. </entry></row>
  222. </tbody></tgroup></informaltable></refsect2>
  223. <refsect2>
  224. <title><anchor id="gimp-dialog-create-action-areav">gimp_dialog_create_action_areav ()</title>
  225. <programlisting>void        gimp_dialog_create_action_areav (<link linkend="GtkDialog">GtkDialog</link> *dialog,
  226.                                              va_list args);</programlisting>
  227. <para>
  228. </para>
  229. <para>
  230.  
  231. The <parameter>va_list</parameter> describing the action_area <link linkend="GtkButton">GtkButton</link>'s has the following format:
  232.  
  233. <informaltable pgwide=1 frame="none" role="struct">
  234. <tgroup cols="2"><colspec colwidth="4*"><colspec colwidth="8*">
  235. <tbody>
  236.  
  237. <row>
  238. <entry><link linkend="gchar">gchar</link> *label,</entry>
  239. <entry>The button's label.</entry>
  240. </row>
  241.  
  242. <row>
  243. <entry><link linkend="GtkSignalFunc">GtkSignalFunc</link> callback,</entry>
  244. <entry>The callback which will be connected to the button's
  245. "clicked" signal</entry>
  246. </row>
  247.  
  248. <row>
  249. <entry><link linkend="gpointer">gpointer</link> data,</entry>
  250. <entry>The callback data which will be used in
  251. <link linkend="gtk-signal-connect">gtk_signal_connect</link>(). If you pass <link linkend="NULL-CAPS">NULL</link>, then the dialog itself will
  252. by passed as <parameter>data</parameter>.</entry>
  253. </row>
  254.  
  255. <row>
  256. <entry><link linkend="GtkObject">GtkObject</link> *slot_object,</entry>
  257. <entry>If you pass a pointer other than <link linkend="NULL-CAPS">NULL</link>, then the button's "clicked"
  258. signal will be connected with <link linkend="gtk-signal-connect-object">gtk_signal_connect_object</link>() instead of
  259. <link linkend="gtk-signal-connect">gtk_signal_connect</link>(). If you want the dialog itself to be the
  260. <parameter>slot_object</parameter>, pass "1".</entry>
  261. </row>
  262.  
  263. <row>
  264. <entry><link linkend="GtkWidget">GtkWidget</link> **widget_ptr,</entry>
  265. <entry>A pointer to store the created button in.</entry>
  266. </row>
  267.  
  268. <row>
  269. <entry><link linkend="gboolean">gboolean</link> default_action,</entry>
  270. <entry><link linkend="TRUE-CAPS">TRUE</link> if this button should grab the default dialog action with
  271. <link linkend="gtk-widget-grab-default">gtk_widget_grab_default</link>().</entry>
  272. </row>
  273.  
  274. <row>
  275. <entry><link linkend="gboolean">gboolean</link> connect_delete,</entry>
  276. <entry><link linkend="TRUE-CAPS">TRUE</link> if the dialog's "delete_event" should be connected to
  277. this button's callback. Usually you will connect to the dialog's
  278. "Cancel" callback. Note that the callback will be called indirectly,
  279. so you don't have to worry about the <link linkend="GdkEvent">GdkEvent</link> pointer which comes
  280. with the "delete_event", as it will be stripped away before your
  281. "Cancel" callback is called.</entry>
  282. </row>
  283.  
  284. </tbody></tgroup></informaltable>
  285.  
  286. </para><informaltable pgwide=1 frame="none" role="params">
  287. <tgroup cols="2">
  288. <colspec colwidth="2*">
  289. <colspec colwidth="8*">
  290. <tbody>
  291. <row><entry align="right"><parameter>dialog</parameter> :</entry>
  292. <entry> The <link linkend="GtkDialog">GtkDialog</link> you want to create the action_area for.
  293. </entry></row>
  294. <row><entry align="right"><parameter>args</parameter> :</entry>
  295. <entry> A <parameter>va_list</parameter> as obtained with <link linkend="va-start">va_start</link>() describing the action_area
  296. buttons.
  297. </entry></row>
  298. </tbody></tgroup></informaltable></refsect2>
  299.  
  300. </refsect1>
  301.  
  302.  
  303.  
  304.  
  305. </refentry>
  306.